1 <sect1 id="appendix.porting.internals" xreflabel="internals">
2 <?dbhtml filename="internals.html"?>
15 <title>Porting to New Hardware or Operating Systems</title>
21 <para>This document explains how to port libstdc++ (the GNU C++ library) to
25 <para>In order to make the GNU C++ library (libstdc++) work with a new
26 target, you must edit some configuration files and provide some new
27 header files. Unless this is done, libstdc++ will use generic
28 settings which may not be correct for your target; even if they are
29 correct, they will likely be inefficient.
32 <para>Before you get started, make sure that you have a working C library on
33 your target. The C library need not precisely comply with any
34 particular standard, but should generally conform to the requirements
35 imposed by the ANSI/ISO standard.
38 <para>In addition, you should try to verify that the C++ compiler generally
39 works. It is difficult to test the C++ compiler without a working
40 library, but you should at least try some minimal test cases.
43 <para>(Note that what we think of as a "target," the library refers to as
44 a "host." The comment at the top of <code>configure.ac</code> explains why.)
48 <sect2 id="internals.os" xreflabel="internals.os">
49 <title>Operating System</title>
51 <para>If you are porting to a new operating system (as opposed to a new chip
52 using an existing operating system), you will need to create a new
53 directory in the <code>config/os</code> hierarchy. For example, the IRIX
54 configuration files are all in <code>config/os/irix</code>. There is no set
55 way to organize the OS configuration directory. For example,
56 <code>config/os/solaris/solaris-2.6</code> and
57 <code>config/os/solaris/solaris-2.7</code> are used as configuration
58 directories for these two versions of Solaris. On the other hand, both
59 Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code>
60 directory. The important information is that there needs to be a
61 directory under <code>config/os</code> to store the files for your operating
65 <para>You might have to change the <code>configure.host</code> file to ensure that
66 your new directory is activated. Look for the switch statement that sets
67 <code>os_include_dir</code>, and add a pattern to handle your operating system
68 if the default will not suffice. The switch statement switches on only
69 the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code>
70 in <code>sparc-sun-solaris2.8</code>. If the new directory is named after the
71 OS portion of the triplet (the default), then nothing needs to be changed.
74 <para>The first file to create in this directory, should be called
75 <code>os_defines.h</code>. This file contains basic macro definitions
76 that are required to allow the C++ library to work with your C library.
79 <para>Several libstdc++ source files unconditionally define the macro
80 <code>_POSIX_SOURCE</code>. On many systems, defining this macro causes
81 large portions of the C library header files to be eliminated
82 at preprocessing time. Therefore, you may have to <code>#undef</code> this
83 macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or
84 <code>__EXTENSIONS__</code>). You won't know what macros to define or
85 undefine at this point; you'll have to try compiling the library and
86 seeing what goes wrong. If you see errors about calling functions
87 that have not been declared, look in your C library headers to see if
88 the functions are declared there, and then figure out what macros you
89 need to define. You will need to add them to the
90 <code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your
91 target. It will not work to simply define these macros in
92 <code>os_defines.h</code>.
95 <para>At this time, there are a few libstdc++-specific macros which may be
99 <para><code>_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99
100 function declarations (which are not covered by specialization below)
101 found in system headers against versions found in the library headers
102 derived from the standard.
105 <para><code>_GLIBCXX_USE_C99_DYNAMIC</code> may be defined to an expression that
106 yields 0 if and only if the system headers are exposing proper support
107 for C99 functions (which are not covered by specialization below). If
108 defined, it must be 0 while bootstrapping the compiler/rebuilding the
112 <para><code>_GLIBCXX_USE_C99_LONG_LONG_CHECK</code> may be defined to 1 to check
113 the set of C99 long long function declarations found in system headers
114 against versions found in the library headers derived from the
118 <para><code>_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC</code> may be defined to an
119 expression that yields 0 if and only if the system headers are
120 exposing proper support for the set of C99 long long functions. If
121 defined, it must be 0 while bootstrapping the compiler/rebuilding the
124 <para><code>_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC</code> may be defined to an
125 expression that yields 0 if and only if the system headers
126 are exposing proper support for the related set of macros. If defined,
127 it must be 0 while bootstrapping the compiler/rebuilding the library.
129 <para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK</code> may be defined
130 to 1 to check the related set of function declarations found in system
131 headers against versions found in the library headers derived from
134 <para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC</code> may be defined
135 to an expression that yields 0 if and only if the system headers
136 are exposing proper support for the related set of functions. If defined,
137 it must be 0 while bootstrapping the compiler/rebuilding the library.
139 <para>Finally, you should bracket the entire file in an include-guard, like
145 #ifndef _GLIBCXX_OS_DEFINES
146 #define _GLIBCXX_OS_DEFINES
151 <para>We recommend copying an existing <code>os_defines.h</code> to use as a
157 <sect2 id="internals.cpu" xreflabel="internals.cpu">
160 <para>If you are porting to a new chip (as opposed to a new operating system
161 running on an existing chip), you will need to create a new directory in the
162 <code>config/cpu</code> hierarchy. Much like the <link linkend="internals.os">Operating system</link> setup,
163 there are no strict rules on how to organize the CPU configuration
164 directory, but careful naming choices will allow the configury to find your
165 setup files without explicit help.
168 <para>We recommend that for a target triplet <code><CPU>-<vendor>-<OS></code>, you
169 name your configuration directory <code>config/cpu/<CPU></code>. If you do this,
170 the configury will find the directory by itself. Otherwise you will need to
171 edit the <code>configure.host</code> file and, in the switch statement that sets
172 <code>cpu_include_dir</code>, add a pattern to handle your chip.
175 <para>Note that some chip families share a single configuration directory, for
176 example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the
177 <code>config/cpu/alpha</code> directory, and there is an entry in the
178 <code>configure.host</code> switch statement to handle this.
181 <para>The <code>cpu_include_dir</code> sets default locations for the files controlling
182 <link linkend="internals.thread_safety">Thread safety</link> and <link linkend="internals.numeric_limits">Numeric limits</link>, if the defaults are not
183 appropriate for your chip.
189 <sect2 id="internals.char_types" xreflabel="internals.char_types">
190 <title>Character Types</title>
192 <para>The library requires that you provide three header files to implement
193 character classification, analogous to that provided by the C libraries
194 <code><ctype.h></code> header. You can model these on the files provided in
195 <code>config/os/generic</code>. However, these files will almost
196 certainly need some modification.
199 <para>The first file to write is <code>ctype_base.h</code>. This file provides
200 some very basic information about character classification. The libstdc++
201 library assumes that your C library implements <code><ctype.h></code> by using
202 a table (indexed by character code) containing integers, where each of
203 these integers is a bit-mask indicating whether the character is
204 upper-case, lower-case, alphabetic, etc. The <code>ctype_base.h</code>
205 file gives the type of the integer, and the values of the various bit
206 masks. You will have to peer at your own <code><ctype.h></code> to figure out
207 how to define the values required by this file.
210 <para>The <code>ctype_base.h</code> header file does not need include guards.
211 It should contain a single <code>struct</code> definition called
212 <code>ctype_base</code>. This <code>struct</code> should contain two type
213 declarations, and one enumeration declaration, like this example, taken
214 from the IRIX configuration:
220 typedef unsigned int mask;
221 typedef int* __to_type;
240 <para>The <code>mask</code> type is the type of the elements in the table. If your
241 C library uses a table to map lower-case numbers to upper-case numbers,
242 and vice versa, you should define <code>__to_type</code> to be the type of the
243 elements in that table. If you don't mind taking a minor performance
244 penalty, or if your library doesn't implement <code>toupper</code> and
245 <code>tolower</code> in this way, you can pick any pointer-to-integer type,
246 but you must still define the type.
249 <para>The enumeration should give definitions for all the values in the above
250 example, using the values from your native <code><ctype.h></code>. They can
251 be given symbolically (as above), or numerically, if you prefer. You do
252 not have to include <code><ctype.h></code> in this header; it will always be
253 included before <code>ctype_base.h</code> is included.
256 <para>The next file to write is <code>ctype_noninline.h</code>, which also does
257 not require include guards. This file defines a few member functions
258 that will be included in <code>include/bits/locale_facets.h</code>. The first
259 function that must be written is the <code>ctype<char>::ctype</code>
260 constructor. Here is the IRIX example:
264 ctype<char>::ctype(const mask* __table = 0, bool __del = false,
266 : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
271 ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
276 <para>There are two parts of this that you might choose to alter. The first,
277 and most important, is the line involving <code>__libc_attr</code>. That is
278 IRIX system-dependent code that gets the base of the table mapping
279 character codes to attributes. You need to substitute code that obtains
280 the address of this table on your system. If you want to use your
281 operating system's tables to map upper-case letters to lower-case, and
282 vice versa, you should initialize <code>_M_toupper</code> and
283 <code>_M_tolower</code> with those tables, in similar fashion.
286 <para>Now, you have to write two functions to convert from upper-case to
287 lower-case, and vice versa. Here are the IRIX versions:
292 ctype<char>::do_toupper(char __c) const
293 { return _toupper(__c); }
296 ctype<char>::do_tolower(char __c) const
297 { return _tolower(__c); }
300 <para>Your C library provides equivalents to IRIX's <code>_toupper</code> and
301 <code>_tolower</code>. If you initialized <code>_M_toupper</code> and
302 <code>_M_tolower</code> above, then you could use those tables instead.
305 <para>Finally, you have to provide two utility functions that convert strings
306 of characters. The versions provided here will always work - but you
307 could use specialized routines for greater performance if you have
308 machinery to do that on your system:
313 ctype<char>::do_toupper(char* __low, const char* __high) const
315 while (__low < __high)
317 *__low = do_toupper(*__low);
324 ctype<char>::do_tolower(char* __low, const char* __high) const
326 while (__low < __high)
328 *__low = do_tolower(*__low);
335 <para>You must also provide the <code>ctype_inline.h</code> file, which
336 contains a few more functions. On most systems, you can just copy
337 <code>config/os/generic/ctype_inline.h</code> and use it on your system.
340 <para>In detail, the functions provided test characters for particular
341 properties; they are analogous to the functions like <code>isalpha</code> and
342 <code>islower</code> provided by the C library.
345 <para>The first function is implemented like this on IRIX:
351 is(mask __m, char __c) const throw()
352 { return (_M_table)[(unsigned char)(__c)] & __m; }
355 <para>The <code>_M_table</code> is the table passed in above, in the constructor.
356 This is the table that contains the bitmasks for each character. The
357 implementation here should work on all systems.
360 <para>The next function is:
366 is(const char* __low, const char* __high, mask* __vec) const throw()
368 while (__low < __high)
369 *__vec++ = (_M_table)[(unsigned char)(*__low++)];
374 <para>This function is similar; it copies the masks for all the characters
375 from <code>__low</code> up until <code>__high</code> into the vector given by
379 <para>The last two functions again are entirely generic:
385 scan_is(mask __m, const char* __low, const char* __high) const throw()
387 while (__low < __high && !this->is(__m, *__low))
394 scan_not(mask __m, const char* __low, const char* __high) const throw()
396 while (__low < __high && this->is(__m, *__low))
405 <sect2 id="internals.thread_safety" xreflabel="internals.thread_safety">
406 <title>Thread Safety</title>
408 <para>The C++ library string functionality requires a couple of atomic
409 operations to provide thread-safety. If you don't take any special
410 action, the library will use stub versions of these functions that are
411 not thread-safe. They will work fine, unless your applications are
415 <para>If you want to provide custom, safe, versions of these functions, there
416 are two distinct approaches. One is to provide a version for your CPU,
417 using assembly language constructs. The other is to use the
418 thread-safety primitives in your operating system. In either case, you
419 make a file called <code>atomicity.h</code>, and the variable
420 <code>ATOMICITYH</code> must point to this file.
423 <para>If you are using the assembly-language approach, put this code in
424 <code>config/cpu/<chip>/atomicity.h</code>, where chip is the name of
425 your processor (see <link linkend="internals.cpu">CPU</link>). No additional changes are necessary to
426 locate the file in this case; <code>ATOMICITYH</code> will be set by default.
429 <para>If you are using the operating system thread-safety primitives approach,
430 you can also put this code in the same CPU directory, in which case no more
431 work is needed to locate the file. For examples of this approach,
432 see the <code>atomicity.h</code> file for IRIX or IA64.
435 <para>Alternatively, if the primitives are more closely related to the OS
436 than they are to the CPU, you can put the <code>atomicity.h</code> file in
437 the <link linkend="internals.os">Operating system</link> directory instead. In this case, you must
438 edit <code>configure.host</code>, and in the switch statement that handles
439 operating systems, override the <code>ATOMICITYH</code> variable to point to
440 the appropriate <code>os_include_dir</code>. For examples of this approach,
441 see the <code>atomicity.h</code> file for AIX.
444 <para>With those bits out of the way, you have to actually write
445 <code>atomicity.h</code> itself. This file should be wrapped in an
446 include guard named <code>_GLIBCXX_ATOMICITY_H</code>. It should define one
447 type, and two functions.
450 <para>The type is <code>_Atomic_word</code>. Here is the version used on IRIX:
454 typedef long _Atomic_word;
457 <para>This type must be a signed integral type supporting atomic operations.
458 If you're using the OS approach, use the same type used by your system's
459 primitives. Otherwise, use the type for which your CPU provides atomic
463 <para>Then, you must provide two functions. The bodies of these functions
464 must be equivalent to those provided here, but using atomic operations:
468 static inline _Atomic_word
469 __attribute__ ((__unused__))
470 __exchange_and_add (_Atomic_word* __mem, int __val)
472 _Atomic_word __result = *__mem;
478 __attribute__ ((__unused__))
479 __atomic_add (_Atomic_word* __mem, int __val)
488 <sect2 id="internals.numeric_limits" xreflabel="internals.numeric_limits">
489 <title>Numeric Limits</title>
491 <para>The C++ library requires information about the fundamental data types,
492 such as the minimum and maximum representable values of each type.
493 You can define each of these values individually, but it is usually
494 easiest just to indicate how many bits are used in each of the data
495 types and let the library do the rest. For information about the
496 macros to define, see the top of <code>include/bits/std_limits.h</code>.
499 <para>If you need to define any macros, you can do so in <code>os_defines.h</code>.
500 However, if all operating systems for your CPU are likely to use the
501 same values, you can provide a CPU-specific file instead so that you
502 do not have to provide the same definitions for each operating system.
503 To take that approach, create a new file called <code>cpu_limits.h</code> in
504 your CPU configuration directory (see <link linkend="internals.cpu">CPU</link>).
510 <sect2 id="internals.libtool" xreflabel="internals.libtool">
511 <title>Libtool</title>
513 <para>The C++ library is compiled, archived and linked with libtool.
514 Explaining the full workings of libtool is beyond the scope of this
515 document, but there are a few, particular bits that are necessary for
519 <para>Some parts of the libstdc++ library are compiled with the libtool
520 <code>--tags CXX</code> option (the C++ definitions for libtool). Therefore,
521 <code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct
522 logic to compile and archive objects equivalent to the C version of libtool,
523 <code>ltcf-c.sh</code>. Some libtool targets have definitions for C but not
524 for C++, or C++ definitions which have not been kept up to date.
527 <para>The C++ run-time library contains initialization code that needs to be
528 run as the library is loaded. Often, that requires linking in special
529 object files when the C++ library is built as a shared library, or
530 taking other system-specific actions.
533 <para>The libstdc++ library is linked with the C version of libtool, even
534 though it is a C++ library. Therefore, the C version of libtool needs to
535 ensure that the run-time library initializers are run. The usual way to
536 do this is to build the library using <code>gcc -shared</code>.
539 <para>If you need to change how the library is linked, look at
540 <code>ltcf-c.sh</code> in the top-level directory. Find the switch statement
541 that sets <code>archive_cmds</code>. Here, adjust the setting for your